home *** CD-ROM | disk | FTP | other *** search
/ Grand Slam 3 / Grand Slam 3.iso / 002 / tfile078.arj / TOPFILE.DOC < prev    next >
Text File  |  1995-08-25  |  21KB  |  441 lines
  1.  
  2.         ╒═════════════════════════════════════════════════════════════╕
  3.         │  ┌───────┐┌──────┐┌──────┐     ┌──────┐┌─┐┌─┐     ┌──────┐  │
  4.         │  └───────┘└──────┘└──────┘     └──────┘└─┘└─┘     └──────┘  │
  5.         │     ┌─┐   ┌─┐  ┌─┐┌──────┐     ┌────┐  ┌─┐┌─┐     ┌──────┐  │
  6.         │     │ │   │ │  │ ││ ┌────┘     │ ┌──┘  │ ││ │     │ ┌────┘  │
  7.         │     │ │   │ └──┘ ││ │          │ │     │ ││ └────┐│ └────┐  │
  8.         │     └─┘   └──────┘└─┘          └─┘     └─┘└──────┘└──────┘  │
  9.         ╘═════════════════════════════════════════════════════ v0.78 ═╛
  10.  
  11.                    A Top Downloaded Files Statistic Producer
  12.                     (c) Copyright 1994, 1995, Dwayne Heaton
  13.  
  14.              ╒═══════════════════════════════════════════════════╕
  15.              │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ Index ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  16.              ╞═══════════════════════════════════════════════════╡
  17.              │ Introduction                                      │
  18.              │   What is TOPFILE?                            1.1 │
  19.              │   System Hardware & software requirements     1.2 │
  20.              │   Disclaimer and Licensing agreement          1.3 │
  21.              │ Installation                                  2.0 │
  22.              │ Usage                                             │
  23.              │   Command Line                                3.1 │
  24.              │   The TOPFILE.CTL file                        3.2 │
  25.              │   The TOPFILE.EXC file                        3.3 │
  26.              │ Bug Reports and Contacting the Author         4.0 │
  27.              │ Credits and Thanks                            5.0 │
  28.              └───────────────────────────────────────────────────┘
  29.  
  30.  
  31.  
  32. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  33. │  1.1 │  What is TOPFILE ? ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  34. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  35.  
  36.   TOPFILE is a 'Top Downloaded Files' ASCII/ANSi/AVATAR bulletin generator.
  37.  
  38.   It was originally written to produce a screen for my users to view, showing
  39.   the most popular files on my system. I know that there are several programs
  40.   out there that also perform the same function, but I wanted to try out my
  41.   programming skills and write my own. Thus, TOPFILE was born....
  42.  
  43.   I designed it to produce the ASCII/ANSi/ATATAR bulletins as quickly as
  44.   possible with the obsolute minumin of configuration. I hope I've suceeded.
  45.  
  46.   And finally, the program is NOT crippled in any way whatsoever, and DOESN'T
  47.   require any registration fees at all :-)
  48.  
  49.  
  50. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  51. │  1.2 │ System hardware and software requirements ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  52. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  53.  
  54.   *  An IBM PC, XT, AT or 100% compatible PC with a hard disk.
  55.   *  Microsoft MS-DOS, IBM PC-DOS or DR-DOS version 3.30 or later. Version
  56.      5.0 or later is recommended.
  57.   *  At least 128KB of RAM available.
  58.  
  59.   *  At the moment TOPFILE only supports the following BBS filebases:
  60.        - Remote Access    Copyright (c) Wantree Development & Andrew Milner
  61.  
  62.   *  TOPFILE has been successfully tested with the file base as used in
  63.      Remote Access v2.00, v2.01 and v2.02
  64.  
  65.   *  TOPFILE has been successfully tested with MS-DOS 5.0, 6.0, 6.2 and
  66.      6.22, 4DOS 5.0 and 5.5, IBM OS/2 WARP, Novell Netware Lite v1.1,
  67.      Novell Netware v3.12 on systems equiped with Intel/AMD 8086, 80286,
  68.      80386 and 80486 processors.
  69.  
  70.   *  OS/2 is a registered trademark of IBM Corporation
  71.      MS-DOS is a registered trademark of Microsoft Corporation
  72.  
  73.      All other programs are copyright and/or trademarked by their
  74.      respective author unless otherwise noted.
  75.  
  76.  
  77. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  78. │  1.3 │ Disclaimer and Licensing Agreement ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  79. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  80.  
  81.     TOPFILE consists of all files contained within the distribution archive.
  82.     Before running TOPFILE, you must read and agree to the following
  83.     conditions. If you do not or can not agree to and accept the following
  84.     conditions, you are prohibited from using TOPFILE.
  85.  
  86.  *  TOPFILE is copyrighted material by Dwayne Heaton and may only be used in
  87.     accordance with the conditions set forth in this license agreement.
  88.  
  89.  *  TOPFILE is distributed as a FREEWARE program.
  90.  
  91.     Permission is granted to any individual or institution to use, copy, or
  92.     redistribute TOPFILE as long as it is not modified and that it is not sold
  93.     for profit.
  94.  
  95.  *  I (Dwayne Heaton) am NOT oligated to provide new versions or support for
  96.     TOPFILE.
  97.  
  98.  *  In the event that future versions of TOPFILE are released, Dwayne Heaton
  99.     reserves the right not to release them under the FREEWARE concept and to
  100.     charge a nominal fee should it be deemed appropriate.
  101.  
  102.  *  Although care has been taken to write and test a program that does what
  103.     this document states, the program is provided as is, without warrenty or
  104.     guarantee of any kind, either expressed or implied, as to the quality or
  105.     performance of this program, except that TOPFILE will occupy disk space.
  106.  
  107.  *  The author of TOPFILE, Dwayne Heaton, is NOT responsible for any (direct
  108.     or indirect) damage or costs, including, but not limited to, lost savings,
  109.     lost profits and loss of data, which may result from the use or the
  110.     inability to use TOPFILE.
  111.  
  112.  *  You are NOT allowed to do any disassembling, reverse engineering, creating
  113.     patches for TOPFILE and things alike.
  114.  
  115.  *  If you use this program, you will constitute your agreement to this
  116.     disclaimer/license.
  117.  
  118.  *  The source code or part of it, is NOT available.
  119.  
  120.  *  All rights reserved worldwide.
  121.  
  122.  
  123. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  124. │  2.0 │ Installation ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  125. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  126.  
  127.   I tried to make using TOPFILE as easy to use as I possibly could. Just
  128.   unpack the archive into one directory, and its ready to use straight away.
  129.  
  130.   A new feature of TOPFILE (as from v0.74) is the ability to configure the
  131.   program to suit your system.
  132.  
  133.   The config file ('TOPFILE.CTL') must be in the same directory that you are
  134.   running TOPFILE from. It doesn't have to exist, but it should exist if you
  135.   want greater control over the program (since it gives you more options than
  136.   the command line). The control (config) file is explained in more detail
  137.   in section 3.2, 'The TOPFILE.CTL file'
  138.  
  139.   TOPFILE will now allow you to specify a list of file names and or file
  140.   areas you wish excluded from the bulletin(s). This file is explained in
  141.   more detail in section 3.3, 'The TOPFILE.EXC file'
  142.  
  143.   You will need to have the RA environment variable set, so that it points
  144.   to your Remote Access system directory, but if you are running RA without
  145.   any problems, this should be already be set  :)
  146.  
  147.   Once you have installed TOPFILE all you need to do is run it to produce
  148.   the ASCII/ANSi/AVATAR bulletin. The bulletins created are placed in the
  149.   main Text Files directory as specified in your RemoteAccess configuration.
  150.  
  151.   You could run TOPFILE after every call to the BBS, or you could run it in
  152.   any daily maintenance events.
  153.  
  154.  
  155.   Note - If you have a large number of file areas and/or files TOPFILE can
  156.          take some time. (Performance is improved if you use a disk caching
  157.          program)
  158.  
  159.          TOPFILE will try and use SHARE to open all files it needs. This
  160.          will allow multi-line BBS's to run it without getting any file
  161.          sharing violations.
  162.  
  163.  
  164. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  165. │  3.1 │ Command Line ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  166. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  167.  
  168.   There are a few command-line options you can use for greater control over
  169.   the program's operation. When used in conjunction with the control file
  170.   these options over-ride any settings in the file.
  171.  
  172.   If you do not specify any options TOPFILE will use its internal defaults
  173.   of ignoring FREE and MISSING files, including every file, not performing
  174.   a secondary sort (see -SORTAREA & -SORTNAME below), generating ASCII and
  175.   ANSi screens and auto detecting the display type..
  176.  
  177.  
  178.   TOPFILE -?              Shows a brief help screen with all options listed
  179.                           on it.
  180.  
  181.           -HELP           Same as above.
  182.  
  183.           -NOFREE         This will tell TOPFILE to exclude any file that
  184.                           is a free download to users in the bulletin.
  185.                           (A free file is one that has been flagged as a
  186.                            free download or any file that is in an Area
  187.                            which has been set to free.)
  188.  
  189.           -USEAREA        This forces TOPFILE to use the area number and
  190.                           area description instead of using the file
  191.                           description. Useful if you have alot of files
  192.                           with borders..
  193.  
  194.           -NOMISSING      This will make TOPFILE to exclude any file that
  195.                           has been flagged as missing.
  196.  
  197.           -NOASCII        Stops TOPFILE producing ASCII bulletins
  198.  
  199.           -NOANSI         Stops TOPFILE producing ANSi bulletins
  200.  
  201.           -NOAVATAR       Stops TOPFILE producing AVATAR bulletins
  202.  
  203.           -MONO           Forces TOPFILE to use its mono-chrome display scheme
  204.  
  205.           -COLOUR         Forces TOPFILE to use its colour display scheme
  206.  
  207.           -SORTNAME       Performs a secondary sort on all files with the
  208.                           same download count, and orders them by filename
  209.  
  210.           -SORTAREA       Performs a secondary sort on all files with the
  211.                           same download count, and orders them by file area
  212.                           number.
  213.  
  214.           -SEC=<num>      The maximium list security to include in the
  215.                           bulletin.
  216.  
  217.  
  218. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  219. │  3.2 │ The TOPFILE.CTL File ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  220. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  221.  
  222.   As said before the control (config) file will allow you to fully configure
  223.   TOPFILE to your system. It will allow you to set all the options that the
  224.   commandline does, but with has several more options.
  225.  
  226.   If this is a new installation just run SETUP.EXE to create an initial
  227.   TOPFILE.CTL file with default settings.
  228.  
  229.   If this is an upgrade installation, run SETUP.EXE to update your existing
  230.   TOPFILE.CTL with any new options. Follow the on screen information.
  231.  
  232.   The options can be in any order, but the option and the value must be
  233.   separated by at least one space. Any line starting with a ';' is counted
  234.   as a comment line and isn't processed.
  235.  
  236.   Here is a list of options you can use, and a description or what they do.
  237.   
  238.    Description         Description type to use.
  239.    IncludeFree         Whether to include free files in the bulletin.
  240.    IncludeMissing      Whether to include missing files in the bulletin.
  241.    ASCII               Produce ASCII bulletins.
  242.    ANSi                Produce ANSi bulletins.
  243.    AVATAR              Produce AVATAR bulletins.
  244.    Colour              Use colour or mono-chrome on local display.
  245.    FileSort            The Top Files secondary sort type.
  246.    AreaSort            The Area Statistics primary sort type.
  247.    HighSecurity        Highest FileArea ListSecurity to include.
  248.    TitleColour         The 'Top xx Files on ..' colour.
  249.    BorderColour        The colour of the box around all the list of files.
  250.    FileColour          Which colour the filename is displayed in.
  251.    CountColour         Colour of the times downloaded count.
  252.    SizeColour          The colour of the size (in Kb) of the file.
  253.    DescriptionColour   The colour you want the file description to be.
  254.    ASC_TopFiles        The filename of the Top Files ASCII bulletin.
  255.    ANS_TopFiles        The filename of the Top Files ANSi bulletin.
  256.    AVT_TopFiles        The filename of the Top Files AVATAR bulletin.
  257.    ASC_AreaStat        The filename of the Area Statistics ASCII bulletin.
  258.    ANS_AreaStat        The filename of the Area Statistics ANSi bulletin.
  259.    AVT_AreaStat        The filename of the Area Statistics AVATAR bulletin.
  260.  
  261.   Description accepts the following values : File, Area
  262.  
  263.   IncludeFree, IncludeMissing, Ascii, Ansi, Colour, Sort accept the following
  264.   values : Yes, No, On, Off, True, False
  265.  
  266.   FileSort accepts the following values : File, Area, None
  267.  
  268.   AreaSort accepts the following calues : None, File, Size, Downloads.
  269.  
  270.   IncludeSysop, UseHandles, UseHidden, ASCII, ANSi, AVATAR and Colour accept
  271.   the following values : Yes or No, On or Off, True or False
  272.  
  273.   A??_TopFiles and A??_AreaStat reconize the following values : No, Off,
  274.   False.  Any thing other these will be interpreted as a filename..
  275.  
  276.   HighSecurity must be an integer, from 0 to 65535.
  277.  
  278.   TitleColour, BorderColour, FileColour, CountColour, SizeColour,
  279.   DescriptionColour accept valid colour names or numbers.
  280.  
  281.   ╓─────────────────── Table of valid names and numbers ────────────────────╖
  282.   ╠════╤══════════╗╔════╤══════════════╗╔════╤════════════╗╔════╤═══════════╣
  283.   ║  0 │ Black    ║║  1 │ Blue         ║║  2 │ Green      ║║  3 │ Cyan      ║
  284.   ║  4 │ Red      ║║  5 │ Magenta      ║║  6 │ Brown      ║║  7 │ LightGray ║
  285.   ║  8 │ DarkGray ║║  9 │ LightBlue    ║║ 10 │ LightGreen ║║ 11 │ LightCyan ║
  286.   ║ 12 │ LightRed ║║ 13 │ LightMagenta ║║ 14 │ Yellow     ║║ 15 │ White     ║
  287.   ╠════╧══════════╝╚════╧══════════════╝╚════╧════════════╝╚════╧═══════════╣
  288.   ╙─────────────────────────────────────────────────────────────────────────╜
  289.  
  290.  
  291. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  292. │  3.3 │ The TOPFILE.EXC File ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  293. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  294.  
  295.   TOPFILE has the ability to use an external file of unwanted file names and
  296.   areas. It will use this list to filter out files and/or areas from the
  297.   'Top Downloaded Files' bulletins.
  298.  
  299.   The exclude file must be called 'TOPFILE.EXC' (without qoutes) and MUST be
  300.   located in the TOPFILE system directory (The directory you run TOPFILE
  301.   from.)
  302.  
  303.   TOPFILE.EXC is a plain ASCII text file, created with any text editor.
  304.   It has a specific format which is as follows:
  305.  
  306.   <exclusion type> <exclusion information>
  307.  
  308.   To exclude a file, the <exclusion type> is 'file' (no quotes, and any case)
  309.   and the <exclusion information> is the file name.
  310.  
  311.    Note:- There _MUST_ only be one file name per file exclusion line, and
  312.           the file name must have no spaces between the base name and the
  313.           extension. File names can be in any case but WILDCARDS ARE NOT
  314.           SUPPORTED.
  315.   
  316.    Examples:-  file ALLFILES.ZIP         is a valid file exclusion
  317.                file READ    .ME          is an invalid file exclusion
  318.                                             (This would be ignored)
  319.                READ.ME                   is an invalid exclude line
  320.                                             (This would be ignored)
  321.                READ    .ME               is invalid exclude line
  322.                                             (This would be ignored)
  323.  
  324.   To exclude a file file, the <exclusion type> is 'area' (no quotes, and any
  325.   case) and the <exclusion information> is the file area or you can specify
  326.   a range of areas to exclude thus <start file area>-<end file area>
  327.  
  328.    Note:- There _MUST_ only be one file area(s) exclusion per area exclusion
  329.           line, and if a range is specified there must be no spaces in the
  330.           definition of the range. Comma's in the area number(s) are not
  331.           tollerated.
  332.  
  333.    Examples:-  area 1                    is a valid single area exclusion
  334.                area 20-40                is a valid area range exclusion
  335.                area 40-20                is a valid area range exclusion, but
  336.                                             it would be converted to 20-40
  337.                area 20 - 40              is an invalid area range exclusion
  338.                1                         is an invalid exclusion line
  339.                                             (This would be ignored)
  340.                20-40                     is an invalid exclusion line
  341.                                             (This would be ignored)
  342.  
  343.   A sample Exclude file may look like this:
  344.   ----------------------------
  345.   file ALLFILES.ZIP
  346.   file ALLFILES.ARJ
  347.   file BBS_AD.ZIP
  348.   area 1
  349.   area 5
  350.   area 20-30
  351.   area 32-33
  352.   ----------------------------
  353.  
  354.   This would exclude any ALLFILES.ZIP, ALLFILES.ARJ and BBS_AD.ZIP files, and
  355.   exclude file areas 1, 5, 20 to 30 and 32 to 33.
  356.  
  357.  
  358. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  359. │  4.0 │ Bug Reports and Contacting the Author ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  360. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  361.  
  362.   Please contact me if you have any bug reports and/or suggestions for
  363.   improvements to TOPFILE.
  364.  
  365.   If you have a bug report, just mail a filled in REPORT.BUG (this file
  366.   should have been included in the distribution archive) to me at one of
  367.   the addresses below.
  368.  
  369.   I'm open to suggestions for support for other BBS software. If you wish
  370.   this please supply the structure of the filebase (and all related files)
  371.   files (PASCAL is prefered, but I can work with C) of the BBS you wish
  372.   supported (Also, could you give me a list of environment variables it
  373.   uses, and what they point to, ie RA points to the Remote Access system
  374.   directory, the config and filebase datafiles). I cannot guarantee it
  375.   will be supported, but you never know.
  376.  
  377.   I can be contacted using a number of different methods:
  378.  
  379.   Page/Leave a message on my BBS:
  380.    Virtual Maddness -- +44-1344-422575 -- 24 hours, 300 to 28800 baud
  381.  
  382.   Send a netmail to me at one of my various AKAs:
  383.    FidoNet    :  2:252/314
  384.    RANet      :  73:7441/13
  385.    PascalNet  :  115:4401/407
  386.    InterNet   :  dwayne@vmadd.demon.co.uk
  387.  
  388.  
  389. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  390. │  5.0 │  Credits and Thanks ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  391. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  392.  
  393.    Thanks to my beta testers for helping me test my progs and for their
  394.    numerous suggestions, helpful criticism and for the multitude of
  395.    bug reports.
  396.  
  397.    Thanks to Andrew Pappas, Michael Devonport and Peter Burnett for their
  398.    help with the Multi-Line BBS support.
  399.  
  400.    Thanks to Peter Burnett for supplying various bits of source code.
  401.  
  402.    Also thanks must go out to all the people who have sent suggestions
  403.    to me (Please keep it up), no names since you know who you are (actually
  404.    the list is too large to be included here)
  405.  
  406.  
  407.  Beta Testers
  408.  ============
  409.  
  410.    Andrew Thomas        Andy's Bulletin Board!    +44-161-343-4730
  411.                         FidoNet    2:250/176
  412.                         RANet     73:7446/15
  413.  
  414.    Dean Rocks           The Happy Hippy BBs       +44-1325-354105
  415.                         FidoNet    2:256/602
  416.                         RANet     73:7447/602
  417.  
  418.    Steven Holme         The Fonty Towers BBS      +44-115-952-7443
  419.                         FidoNet    2:2503/216     +44-115-955-4440
  420.                                    2:2503/226
  421.                         RANet     73:7444/22
  422.  
  423.    Peter Burnett        Neverland eXpress         +44-1424-853361
  424.                         FidoNet    2:441/80
  425.                         RANet     73:7441/206
  426.  
  427.    Michael Devonport    Midnite Madness BBS       +44-181-287-5901
  428.                         FidoNet    2:254/301
  429.                         RANet     73:7441/15
  430.  
  431.    Simon Cansick        Guru-Ten BBS              +44-1535-691734
  432.                         FidoNet    2:250/364      +44-1535-691735
  433.                                    2:250/365
  434.                         RANet     73:7448/13
  435.  
  436.  
  437. ╒═════════════════════════════════════════════════════════════════════════════╕
  438. │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ End of File TOPFILE.DOC ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  439. ╘═════════════════════════════════════════════════════════════════════════════╛
  440.  
  441.